home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / lists.doc < prev    next >
Text File  |  1996-09-07  |  18KB  |  631 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/AddSorted
  4. dopus5.library/Att_ChangeNodeName
  5. dopus5.library/Att_FindNode
  6. dopus5.library/Att_FindNodeData
  7. dopus5.library/Att_FindNodeNumber
  8. dopus5.library/Att_NewList
  9. dopus5.library/Att_NewNode
  10. dopus5.library/Att_NodeCount
  11. dopus5.library/Att_NodeDataNumber
  12. dopus5.library/Att_NodeName
  13. dopus5.library/Att_NodeNumber
  14. dopus5.library/Att_PosNode
  15. dopus5.library/Att_RemList
  16. dopus5.library/Att_RemNode
  17. dopus5.library/FindNameI
  18. dopus5.library/GetSemaphore
  19. dopus5.library/InitListLock
  20. dopus5.library/IsListLockEmpty
  21. dopus5.library/LockAttList
  22. dopus5.library/SwapListNodes
  23. dopus5.library/UnlockAttList
  24. dopus5.library/AddSorted                             dopus5.library/AddSorted
  25.  
  26.     NAME
  27.         AddSorted - add a node to a list in alphabetical order
  28.  
  29.     SYNOPSIS
  30.         AddSorted(list, node)
  31.                    A0    A1
  32.  
  33.         void AddSorted(struct List *, struct Node *);
  34.  
  35.     FUNCTION
  36.         This function adds a Node to a List, in alphabetical order based on
  37.         ln_Name.
  38.  
  39.     INPUTS
  40.         list - List to add Node to
  41.         node - Node to add
  42.  
  43.     RESULT
  44.         The node is inserted in the list in its alphabetical position.
  45.         ALL the nodes in the list must have a valid ln_Name, or this routine
  46.         will cause enforcer hits.
  47.  
  48.     NOTES
  49.         This routine uses a simple insertion sort based on strcmpi(). As such,
  50.         it is neither terrible efficient, or locale-sensitive.
  51.  
  52.     SEE ALSO
  53.         exec.library/Insert()
  54.  
  55. dopus5.library/Att_ChangeNodeName           dopus5.library/Att_ChangeNodeName
  56.  
  57.     NAME
  58.         Att_ChangeNodeName - change the name of a node
  59.  
  60.     SYNOPSIS
  61.         Att_ChangeNodeName(node, name)
  62.                             A0    A1
  63.  
  64.         void Att_ChangeNodeName(Att_Node *, char *);
  65.  
  66.     FUNCTION
  67.         Frees the old name of the node and copies the new name.
  68.  
  69.     INPUTS
  70.         node - Att_Node to change name for
  71.         name - new name of the node
  72.  
  73.     RESULT
  74.         The new name is copied and installed.
  75.  
  76.     SEE ALSO
  77.         Att_NewNode()
  78.  
  79. dopus5.library/Att_FindNode                       dopus5.library/Att_FindNode
  80.  
  81.     NAME
  82.         Att_FindNode - find a node by number
  83.  
  84.     SYNOPSIS
  85.         Att_FindNode(list, number)
  86.                       A0     D0
  87.  
  88.         Att_Node *Att_FindNode(Att_List *, long);
  89.  
  90.     FUNCTION
  91.         This routine finds the specified node in the list and returns a
  92.         pointer to it.
  93.  
  94.     INPUTS
  95.         list - list to search
  96.         number - cardinal number of the node to find
  97.  
  98.     RESULT
  99.         Returns the specified Att_Node or NULL if not found.
  100.  
  101.     NOTES
  102.         This routine can also work on normal Lists with proper type-casting.
  103.  
  104.     SEE ALSO
  105.         Att_NewNode(), Att_NodeName()
  106.  
  107. dopus5.library/Att_FindNodeData               dopus5.library/Att_FindNodeData
  108.  
  109.     NAME
  110.         Att_FindNodeData - find a node by its data
  111.  
  112.     SYNOPSIS
  113.         Att_FindNodeData(list, data)
  114.                           A0    D0
  115.  
  116.         Att_Node *Att_FindNodeData(Att_List *, ULONG);
  117.  
  118.     FUNCTION
  119.         This function searches the list for a node with data that matches
  120.         the supplied ULONG value (the data is specified with the Att_NewNode()
  121.         function).
  122.  
  123.     INPUTS
  124.         list - list to search
  125.         data - data to look for
  126.  
  127.     RESULT
  128.         Returns the Att_Node if found, otherwise NULL.
  129.  
  130.     SEE ALSO
  131.         Att_NewNode()
  132.  
  133. dopus5.library/Att_FindNodeNumber           dopus5.library/Att_FindNodeNumber
  134.  
  135.     NAME
  136.         Att_FindNodeNumber - find cardinal number of a node
  137.  
  138.     SYNOPSIS
  139.         Att_FindNodeNumber(list, node)
  140.                             A0    A1
  141.  
  142.         long Att_FindNodeNumber(Att_List *, Att_Node *);
  143.  
  144.     FUNCTION
  145.         This routine searches the list for the specified node, and returns
  146.         the offset from the beginning of the list.
  147.  
  148.     INPUTS
  149.         list - list to search
  150.         node - node to look for
  151.  
  152.     RESULT
  153.         Returns the cardinal number of the node or -1 if not found.
  154.  
  155.     NOTES
  156.         This routine can also work on normal Lists with proper type-casting.
  157.  
  158.     SEE ALSO
  159.         Att_NewNode()
  160.  
  161. dopus5.library/Att_NewList                         dopus5.library/Att_NewList
  162.  
  163.     NAME
  164.         Att_NewList - create a new list
  165.  
  166.     SYNOPSIS
  167.         Att_NewList(flags)
  168.                      D0
  169.  
  170.         Att_List *Att_NewList(ULONG);
  171.  
  172.     FUNCTION
  173.         Creates a new Att_List structure, which you use in conjunction with
  174.         Att_Nodes. These functions provide a convenient way of dynamically
  175.         allocating members of lists and performing searches and sorts on them.
  176.  
  177.     INPUTS
  178.         flags - control flags. Currently valid values are :
  179.  
  180.                     LISTF_LOCK  - list is to be shared and requires locking
  181.                     LISTF_POOL  - use memory pooling for nodes and names
  182.  
  183.                 If you specify LISTF_LOCK, a semaphore will be initialised for
  184.                 this list. Any of the list management functions in the 
  185.                 dopus5.library will lock the semaphore before accessing the
  186.                 list.
  187.  
  188.                 If you specify LISTF_POOL, a small memory pool will be used
  189.                 to allocate list nodes and node names, which can result in
  190.                 greater speed and less memory fragmentation.
  191.  
  192.     RESULT
  193.         Returns pointer to an Att_List structure or NULL for failure.
  194.  
  195.     SEE ALSO
  196.         Att_RemList(), exec.library/NewList()
  197.  
  198. dopus5.library/Att_NewNode                         dopus5.library/Att_NewNode
  199.  
  200.     NAME
  201.         Att_NewNode - add a new node to a list
  202.  
  203.     SYNOPSIS
  204.         Att_NewNode(list, name, data, flags)
  205.                      A0    A1    D0    D1
  206.  
  207.         Att_Node *Att_NewNode(Att_List *, char *, ULONG, ULONG);
  208.  
  209.     FUNCTION
  210.         This routine allocates a new node and adds it to the specified list.
  211.         It can also allocate and copy a name for the node, and store
  212.         user-defined data with it. The new node can be added to the list
  213.         sorted in several ways.
  214.  
  215.     INPUTS
  216.         list - list to add node to
  217.         name - name for the node (will be copied)
  218.         data - user-defined data for the node
  219.         flags - control flags. Currently valid flags are:
  220.  
  221.                     ADDNODEF_SORT       - sort names alphabetically
  222.  
  223.                     ADDNODEF_EXCLUSIVE  - name must be exclusive; if a node
  224.                                           already exists with this name, the
  225.                                           call will fail. Only works in
  226.                                           conjunction with ADDNODEF_SORT.
  227.  
  228.                     ADDNODEF_NUMSORT    - the node name is taken to be an
  229.                                           ascii string containing a number,
  230.                                           and the sort is based on numerical
  231.                                           order rather than ascii order (so
  232.                                           that 10 would come after 1 rather
  233.                                           than before).
  234.  
  235.                     ADDNODEF_PRI        - sort is based on priority. If you
  236.                                           specify this flag, the 'data'
  237.                                           parameter is taken to be the node's
  238.                                           priority.
  239.  
  240.                 If no sorting flags are specified, the node is added to the
  241.                 end of the list.
  242.  
  243.     RESULT
  244.         If successful, the new Att_Node is returned.
  245.  
  246.     SEE ALSO
  247.         Att_NewList(), Att_RemNode()
  248.  
  249. dopus5.library/Att_NodeCount                     dopus5.library/Att_NodeCount
  250.  
  251.     NAME
  252.         Att_NodeCount - count the nodes in a list
  253.  
  254.     SYNOPSIS
  255.         Att_NodeCount(list)
  256.                        A0
  257.  
  258.         long Att_NodeCount(Att_List *);
  259.  
  260.     FUNCTION
  261.         Returns the number of nodes in the list.
  262.  
  263.     INPUTS
  264.         list - list to count
  265.  
  266.     NOTES
  267.         This routine can also work on normal Lists with proper type-casting.
  268.  
  269.     SEE ALSO
  270.         Att_NewNode()
  271.  
  272. dopus5.library/Att_NodeDataNumber           dopus5.library/Att_NodeDataNumber
  273.  
  274.     NAME
  275.         Att_NodeDataNumber - find cardinal number of a node
  276.  
  277.     SYNOPSIS
  278.         Att_NodeDataNumber(list, data)
  279.                             A0    D0
  280.  
  281.         long Att_NodeDataNumber(Att_List *, ULONG);
  282.  
  283.     FUNCTION
  284.         This routine is similar to Att_FindNodeNumber(), except that it takes
  285.         a ULONG value and searches the list for a node with that value as
  286.         it's 'data' (the data specified in the call to Att_NewNode).
  287.  
  288.     INPUTS
  289.         list - list to search
  290.         data - node data to look for
  291.  
  292.     RESULT
  293.         Returns the Att_Node if found, or NULL.
  294.  
  295.     SEE ALSO
  296.         Att_NewNode(), Att_FindNodeNumber()
  297.  
  298. dopus5.library/Att_NodeName                       dopus5.library/Att_NodeName
  299.  
  300.     NAME
  301.         Att_NodeName - find a node name by number
  302.  
  303.     SYNOPSIS
  304.         Att_NodeName(list, number)
  305.                       A0     D0
  306.  
  307.         char *Att_NodeName(Att_List *, long);
  308.  
  309.     FUNCTION
  310.         This routine is similar to Att_FindNode() except that it returns
  311.         a pointer to the node's name rather than the node itself.
  312.  
  313.     INPUTS
  314.         list - list to search
  315.         number - cardinal number of the node to find
  316.  
  317.     RESULT
  318.         Returns a pointer to the node's name, or NULL if not found.
  319.  
  320.     NOTES
  321.         This routine can also work on normal Lists with proper type-casting.
  322.  
  323.     SEE ALSO
  324.         Att_NewNode(), Att_FindNode()
  325.  
  326. dopus5.library/Att_NodeNumber                    dopus5.library/Att_NodeNumber
  327.  
  328.     NAME
  329.         Att_NodeNumber - find cardinal number of node by name
  330.  
  331.     SYNOPSIS
  332.         Att_NodeNumber(list, name)
  333.                         A0    A1
  334.  
  335.         long Att_NodeNumber(Att_List *, char *);
  336.  
  337.     FUNCTION
  338.         This routine is similar to Att_FindNodeNumber(), except that you
  339.         specify a name to search for rather than a node pointer.
  340.  
  341.     INPUTS
  342.         list - list to search
  343.         name - name of node to search for
  344.  
  345.     RESULT
  346.         Returns the cardinal number of the node or -1 if not found.
  347.  
  348.     NOTES
  349.         This routine can also work on normal Lists with proper type-casting.
  350.         The search is not case-sensitive.
  351.  
  352.     SEE ALSO
  353.         Att_NewNode(), Att_FindNodeNumber()
  354.  
  355. dopus5.library/Att_PosNode                         dopus5.library/Att_PosNode
  356.  
  357.     NAME
  358.         Att_PosNode - reposition an Att_Node in an Att_List
  359.  
  360.     SYNOPSIS
  361.         Att_PosNode(list, node, before)
  362.                      A0    A1    A2
  363.  
  364.         void Att_PosNode(Att_List *, Att_Node *, Att_Node *);
  365.  
  366.     FUNCTION
  367.         This routine removes an Att_Node from its current position and
  368.         re-inserts it in the list in a new position.
  369.  
  370.     INPUTS
  371.         list - Att_List containing node
  372.         node - Att_Node to reposition
  373.         before - Att_Node to re-insert the node before
  374.  
  375.     RESULT
  376.         The node is inserted in the list before the supplied node.
  377.  
  378.     SEE ALSO
  379.         Att_NewNode()
  380.  
  381. dopus5.library/Att_RemList                         dopus5.library/Att_RemList
  382.  
  383.     NAME
  384.         Att_RemList - free an entire Att_List
  385.  
  386.     SYNOPSIS
  387.         Att_RemList(list, flags)
  388.                      A0     D0
  389.  
  390.         void Att_RemList(Att_List *, long);
  391.  
  392.     FUNCTION
  393.         This function releases all the memory used by an Att_List, including
  394.         freeing all of the Att_Nodes attached to it.
  395.  
  396.     INPUTS
  397.         list - Att_List to free
  398.         flags - control flags. Current flag values are :
  399.  
  400.                     REMLISTF_FREEDATA  - If you specify this flag, the data
  401.                                          pointers of each of the nodes will
  402.                                          be automatically freed with FreeVec().
  403.                                          Therefore, if you use this feature,
  404.                                          the data you supply to Att_NewNode()
  405.                                          MUST have been allocated with
  406.                                          AllocVec().
  407.  
  408.                     REMLISTF_SAVELIST  - If you specify this flag, only the
  409.                                          nodes of the list will be freed. The
  410.                                          Att_List itself will be reinitialised,
  411.                                          ready for use.
  412.  
  413.     RESULT
  414.         The list nodes and optionally the list itself is freed.
  415.  
  416.     SEE ALSO
  417.         Att_NewList(), Att_NewNode(), Att_RemNode()
  418.  
  419. dopus5.library/Att_RemNode                         dopus5.library/Att_RemNode
  420.  
  421.     NAME
  422.         Att_RemNode - remove a node from a list
  423.  
  424.     SYNOPSIS
  425.         Att_RemNode(node)
  426.                      A0
  427.  
  428.         void Att_RemNode(Att_Node *);
  429.  
  430.     FUNCTION
  431.         This function removes the specified node from its list, and frees
  432.         the name copy and node structure.
  433.  
  434.     INPUTS
  435.         node - node to free
  436.  
  437.     RESULT
  438.         The node is removed and freed. The node data is NOT freed by this
  439.         routine.
  440.  
  441.     SEE ALSO
  442.         Att_NewNode(), Att_RemList()
  443.  
  444. dopus5.library/FindNameI                             dopus5.library/FindNameI
  445.  
  446.     NAME
  447.         FindNameI - find a node by name
  448.  
  449.     SYNOPSIS
  450.         FindNameI(list, name)
  451.                    A0    A1
  452.  
  453.         struct Node *FindNameI(struct List *, char *);
  454.  
  455.     FUNCTION
  456.         This routine is similar to the exec.library/FindName routine, except
  457.         that the comparison used in FindNameI() is not case-sensitive.
  458.  
  459.     INPUTS
  460.         list - list to search
  461.         name - name to search for
  462.  
  463.     RESULT
  464.         Returns pointer to the node if found, otherwise NULL.
  465.  
  466.     SEE ALSO
  467.         exec.library/FindName()
  468.  
  469. dopus5.library/GetSemaphore                       dopus5.library/GetSemaphore
  470.  
  471.     NAME
  472.         GetSemaphore - lock a semaphore
  473.  
  474.     SYNOPSIS
  475.         GetSemaphore(semaphore, flags, unused)
  476.                         A0       D0      A1
  477.  
  478.         long GetSemaphore(struct SignalSemaphore *, long, APTR);
  479.  
  480.     FUNCTION
  481.         This routine locks or attempts to lock the given Semaphore. This
  482.         routine fixes some bugs that the exec.library Semaphore routines
  483.         have under some versions of the OS.
  484.  
  485.     INPUTS
  486.         semaphore - Semaphore to lock
  487.         flags - control flags. Valid flags are :
  488.  
  489.                     SEMF_SHARED     - lock in shared mode
  490.                     SEMF_EXCLUSIVE  - lock in exclusive mode
  491.                     SEMF_ATTEMPT    - only attempt to lock
  492.  
  493.         unused - must be NULL
  494.  
  495.     RESULT
  496.         Returns TRUE if the Semaphore was successfully locked. If SEMF_ATTEMPT
  497.         is not specified, this routine will block until the Semaphore is
  498.         available, and will always return TRUE.
  499.  
  500.     NOTES
  501.         To unlock a Semaphore locked with this function, use the standard
  502.         exec.library ReleaseSemaphore() call.
  503.  
  504.     SEE ALSO
  505.         exec.library/ObtainSemaphore(), exec.library/ObtainSemaphoreShared(),
  506.         exec.library/AttemptSemaphore(), exec.library/AttemptSemaphoreShared(),
  507.         exec.library/ReleaseSemaphore()
  508.  
  509. dopus5.library/InitListLock                       dopus5.library/InitListLock
  510.  
  511.     NAME
  512.         InitListLock - initialise a list/lock pair
  513.  
  514.     SYNOPSIS
  515.         InitListLock(ll, unused)
  516.                      A0     A1
  517.  
  518.         void InitListLock(struct ListLock *, APTR);
  519.  
  520.     FUNCTION
  521.         A ListLock is a convenient structure that ties a List to a Semaphore.
  522.         This routine initialises both with the one call.
  523.  
  524.     INPUTS
  525.         ll - ListLock to initialised
  526.         unused - must be NULL
  527.  
  528.     RESULT
  529.         The List and the Semaphore in the ListLock are initialised.
  530.  
  531.     SEE ALSO
  532.         exec.library/NewList(), exec.library/InitSemaphore()
  533.  
  534. dopus5.library/IsListLockEmpty                 dopus5.library/IsListLockEmpty
  535.  
  536.     NAME
  537.         IsListLockEmpty - see if a list is empty
  538.  
  539.     SYNOPSIS
  540.         IsListLockEmpty(ll)
  541.                         A0
  542.  
  543.         BOOL IsListLockEmpty(struct ListLock *);
  544.  
  545.     FUNCTION
  546.         This routine is equivalent to the IsListEmpty() macro, except that
  547.         it locks the list in shared mode before accessing it.
  548.  
  549.     INPUTS
  550.         ll - ListLock to test
  551.  
  552.     RESULT
  553.         Returns TRUE if the list is empty.
  554.  
  555.     SEE ALSO
  556.         InitListLock(), exec.library/IsListEmpty()
  557.  
  558. dopus5.library/LockAttList                         dopus5.library/LockAttList
  559.  
  560.     NAME
  561.         LockAttList - lock an Att_List
  562.  
  563.     SYNOPSIS
  564.         LockAttList(list, exclusive)
  565.                      A0      D0
  566.  
  567.         void LockAttList(Att_List *, BOOL);
  568.  
  569.     FUNCTION
  570.         If an Att_List was created with the LISTF_LOCK flag, this routine can
  571.         be used to lock the list.
  572.  
  573.     INPUTS
  574.         list - Att_List to lock
  575.         exclusive - set to TRUE if you want exclusive access
  576.  
  577.     RESULT
  578.         This routine will block until the list can be locked, and then return.
  579.         You must call UnlockAttList() to unlock the list when you have
  580.         finished with it.
  581.  
  582.     SEE ALSO
  583.         Att_NewList(), UnlockAttList()
  584.  
  585. dopus5.library/SwapListNodes                     dopus5.library/SwapListNodes
  586.  
  587.     NAME
  588.         SwapListNodes - swap two nodes in a list around
  589.  
  590.     SYNOPSIS
  591.         SwapListNodes(list, node1, node2);
  592.                        A0     A1     A2
  593.  
  594.         void SwapListNodes(struct List *, struct Node *, struct Node *);
  595.  
  596.     FUNCTION
  597.         This routine exchanges the positions of two nodes in a list.
  598.  
  599.     INPUTS
  600.         list - List containing the nodes
  601.         node1 - first node to swap
  602.         node2 - second node to swap
  603.  
  604.     RESULT
  605.         The nodes' positions will be exchanged.
  606.  
  607. dopus5.library/UnlockAttList                     dopus5.library/UnlockAttList
  608.  
  609.     NAME
  610.         UnlockAttList - unlock an Att_List
  611.  
  612.     SYNOPSIS
  613.         UnlockAttList(list)
  614.                        A0
  615.  
  616.         void UnlockAttList(Att_List *);
  617.  
  618.     FUNCTION
  619.         This routine unlocks an Att_List that was locked with LockAttList().
  620.  
  621.     INPUTS
  622.         list - list to unlock
  623.  
  624.     RESULT
  625.         The list is unlocked. Calls to LockAttList() are nested, so you must
  626.         unlock the list as many times as you locked it.
  627.  
  628.     SEE ALSO
  629.         LockAttList()
  630.  
  631.